//! # RustCloud 核心特性定义
//!
//! 该模块定义了 RustCloud 微服务框架的所有核心 trait 和相关数据结构。
//! 这些 trait 提供了服务注册发现、负载均衡、熔断器、传输层、指标收集等
//! 微服务治理功能的抽象接口。
//!
//! ## 主要组件
//!
//! * **服务注册发现**: `ServiceRegistry` trait，支持服务实例的注册、发现和监听
//! * **负载均衡**: `LoadBalancer` trait，提供多种负载均衡策略
//! * **熔断器**: `CircuitBreaker` trait，实现服务保护和故障隔离
//! * **传输层**: `Transport` trait，抽象化网络传输实现
//! * **指标收集**: `MetricsCollector` trait，支持监控指标的收集和导出
//! * **分布式追踪**: `TracingProvider` trait，实现请求链路追踪
//! * **服务代理**: `ServiceProxy` trait，提供高级的服务调用能力
//!
//! ## 设计原则
//!
//! * **异步优先**: 所有 trait 都基于 async/await 设计，支持高并发
//! * **可扩展性**: 通过 trait 设计支持多种实现，便于扩展和定制
//! * **类型安全**: 充分利用 Rust 的类型系统确保编译时安全
//! * **性能优化**: 最小化内存分配，支持零拷贝操作
//! * **容错设计**: 内置错误处理和恢复机制
//!
//! ## 使用示例
//!
//! ```rust
//! use rustcloud_core::traits::*;
//! use rustcloud_core::{ServiceInstance, Request};
//!
//! // 实现自定义的负载均衡器
//! struct CustomLoadBalancer;
//!
//! #[async_trait::async_trait]
//! impl LoadBalancer for CustomLoadBalancer {
//!     async fn select(
//!         &self,
//!         service_name: &str,
//!         instances: &[ServiceInstance],
//!     ) -> rustcloud_core::ServiceResult<Option<ServiceInstance>> {
//!         // 自定义选择逻辑
//!         Ok(instances.first().cloned())
//!     }
//!     
//!     fn name(&self) -> &str {
//!         "custom-lb"
//!     }
//!
//!     fn get_strategy_info(&self) -> StrategyInfo {
//!         StrategyInfo {
//!             name: "Custom".to_string(),
//!             description: "自定义负载均衡策略".to_string(),
//!             requires_session_affinity: false,
//!             supports_weighted_routing: true,
//!         }
//!     }
//! }
//! ```

use async_trait::async_trait;
use serde::{Serialize, Deserialize};
use std::collections::HashMap;
use std::time::Duration;
use crate::{Request, Response, ServiceInstance, ServiceResult, CircuitBreakerState, CircuitBreakerMetrics, EnvironmentFilter};

/// 健康检查类型枚举
///
/// 定义了支持的健康检查方式，用于监控服务实例的运行状态。
/// 不同的检查类型适用于不同的服务类型和部署环境。
///
/// # 检查类型说明
///
/// * `Http` - HTTP/HTTPS 健康检查，适用于 Web 服务和 API 服务
/// * `Tcp` - TCP 端口连通性检查，适用于数据库和消息队列等服务
/// * `Script` - 自定义脚本检查，适用于复杂的健康检查逻辑
///
/// # 使用场景
///
/// * **HTTP检查**: 检查 API 服务的 `/health` 端点
/// * **TCP检查**: 验证数据库端口是否可访问
/// * **脚本检查**: 执行自定义健康检查逻辑，如检查磁盘空间、内存使用等
///
/// # 使用示例
///
/// ```rust
/// use rustcloud_core::traits::HealthCheckType;
///
/// // HTTP健康检查
/// let http_check = HealthCheckType::Http {
///     path: "/health".to_string(),
///     method: "GET".to_string(),
/// };
///
/// // TCP端口检查
/// let tcp_check = HealthCheckType::Tcp;
///
/// // 自定义脚本检查
/// let script_check = HealthCheckType::Script {
///     command: "./health_check.sh".to_string(),
/// };
/// ```
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum HealthCheckType {
    /// HTTP/HTTPS 健康检查
    /// 
    /// 通过发送 HTTP 请求到指定路径来检查服务健康状态。
    /// 通常检查特定的健康检查端点，如 `/health`、`/ping` 等。
    Http { 
        /// 健康检查的路径，如 "/health"
        path: String, 
        /// HTTP 方法，通常是 "GET" 或 "HEAD"
        method: String 
    },
    
    /// TCP 端口连通性检查
    /// 
    /// 通过建立 TCP 连接来验证服务端口是否可用。
    /// 适用于数据库、消息队列等不提供 HTTP 接口的服务。
    Tcp,
    
    /// 自定义脚本健康检查
    /// 
    /// 执行自定义脚本或命令来检查服务健康状态。
    /// 脚本应该返回 0 表示健康，非 0 表示不健康。
    Script { 
        /// 要执行的命令或脚本路径
        command: String 
    },
}

/// 健康检查配置
///
/// 定义了健康检查的详细配置参数，包括检查类型、频率、超时时间和阈值设置。
/// 这些参数控制着健康检查的行为和服务实例状态的判断逻辑。
///
/// # 配置参数说明
///
/// * `check_type` - 健康检查类型（HTTP、TCP、脚本）
/// * `endpoint` - 检查目标端点或地址
/// * `interval` - 检查间隔时间
/// * `timeout` - 单次检查超时时间
/// * `failure_threshold` - 连续失败次数阈值，超过后标记为不健康
/// * `success_threshold` - 连续成功次数阈值，超过后标记为健康
///
/// # 状态转换逻辑
///
/// ```text
/// 健康状态 --[连续失败 >= failure_threshold]--> 不健康状态
/// 不健康状态 --[连续成功 >= success_threshold]--> 健康状态
/// ```
///
/// # 使用示例
///
/// ```rust
/// use rustcloud_core::traits::{HealthCheck, HealthCheckType};
/// use std::time::Duration;
///
/// let health_check = HealthCheck {
///     check_type: HealthCheckType::Http {
///         path: "/health".to_string(),
///         method: "GET".to_string(),
///     },
///     endpoint: "http://127.0.0.1:8080".to_string(),
///     interval: Duration::from_secs(30),      // 每30秒检查一次
///     timeout: Duration::from_secs(5),        // 5秒超时
///     failure_threshold: 3,                   // 连续3次失败标记为不健康
///     success_threshold: 2,                   // 连续2次成功标记为健康
/// };
/// ```
///
/// # 最佳实践
///
/// * **间隔时间**: 不宜过短，避免对服务造成过大压力
/// * **超时设置**: 应小于间隔时间，避免检查重叠
/// * **阈值设置**: 失败阈值不宜过小，成功阈值不宜过大
/// * **端点选择**: 健康检查端点应轻量、快速响应
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HealthCheck {
    /// 健康检查类型
    pub check_type: HealthCheckType,
    /// 检查目标端点
    pub endpoint: String,
    /// 检查间隔时间
    pub interval: Duration,
    /// 单次检查超时时间
    pub timeout: Duration,
    /// 失败阈值（连续失败多少次后标记为不健康）
    pub failure_threshold: u32,
    /// 成功阈值（连续成功多少次后标记为健康）
    pub success_threshold: u32,
}

/// 服务过滤器
///
/// 用于在服务发现过程中对服务实例进行过滤和筛选的配置类。
/// 支持基于健康状态、元数据、版本、环境、权重等多种维度的过滤条件。
/// 过滤器采用链式调用的设计模式，便于组合多个过滤条件。
///
/// # 过滤维度
///
/// * **健康状态过滤** - 只返回健康的服务实例
/// * **元数据过滤** - 基于键值对匹配服务实例的元数据
/// * **版本过滤** - 基于版本号筛选服务实例
/// * **集群过滤** - 基于集群名称筛选服务实例
/// * **环境过滤** - 基于环境配置筛选服务实例
/// * **权重过滤** - 基于最小权重阈值筛选服务实例
/// * **数量限制** - 限制返回的最大实例数量
///
/// # 过滤逻辑
///
/// 所有过滤条件都使用 AND 逻辑，即服务实例必须满足所有设置的过滤条件才会被保留。
/// 过滤优先级：健康状态 → 元数据 → 版本 → 集群 → 环境 → 权重 → 数量限制。
///
/// # 使用示例
///
/// ```rust
/// use rustcloud_core::traits::ServiceFilter;
/// use rustcloud_core::EnvironmentFilter;
///
/// // 创建复合过滤器
/// let filter = ServiceFilter::new()
///     .healthy_only(true)                    // 只要健康实例
///     .with_version("v1.2.0")               // 指定版本
///     .with_metadata("region", "us-west-1") // 指定区域
///     .with_min_weight(0.5)                 // 最小权重50%
///     .with_max_instances(10);               // 最多10个实例
///
/// // 检查实例是否匹配过滤条件
/// let instance = create_test_instance();
/// if filter.matches(&instance) {
///     println!("实例通过过滤条件");
/// }
/// ```
///
/// # 性能考虑
///
/// * 过滤操作在内存中进行，性能优异
/// * 建议优先使用健康状态过滤以减少后续过滤的数据量
/// * 元数据过滤使用HashMap查找，时间复杂度O(1)
/// * 权重排序使用快速排序，时间复杂度O(n log n)
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ServiceFilter {
    /// 是否只返回健康的实例（默认为true）
    pub healthy_only: bool,
    /// 元数据过滤条件（键值对匹配）
    pub metadata_filters: HashMap<String, String>,
    /// 版本过滤条件（精确匹配）
    pub version_filter: Option<String>,
    /// 集群过滤条件（精确匹配）
    pub cluster_filter: Option<String>,
    /// 环境过滤器
    pub environment_filter: Option<EnvironmentFilter>,
    /// 最小权重阈值
    pub min_weight: Option<f64>,
    /// 最大实例数限制
    pub max_instances: Option<usize>,
}

impl Default for ServiceFilter {
    fn default() -> Self {
        Self {
            healthy_only: true,
            metadata_filters: HashMap::new(),
            version_filter: None,
            cluster_filter: None,
            environment_filter: None,
            min_weight: None,
            max_instances: None,
        }
    }
}

impl ServiceFilter {
    /// 创建新的服务过滤器
    /// 返回具有默认配置的过滤器实例
    pub fn new() -> Self {
        Self::default()
    }
    
    /// 设置只返回健康实例
    /// 用于启用或禁用健康状态过滤
    pub fn healthy_only(mut self, healthy_only: bool) -> Self {
        self.healthy_only = healthy_only;
        self
    }
    
    /// 添加元数据过滤条件
    /// 基于键值对匹配服务实例的元数据
    pub fn with_metadata(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.metadata_filters.insert(key.into(), value.into());
        self
    }
    
    /// 设置版本过滤条件
    /// 只返回指定版本的服务实例
    pub fn with_version(mut self, version: impl Into<String>) -> Self {
        self.version_filter = Some(version.into());
        self
    }
    
    /// 设置环境过滤条件
    /// 基于环境配置筛选服务实例
    pub fn with_environment_filter(mut self, env_filter: EnvironmentFilter) -> Self {
        self.environment_filter = Some(env_filter);
        self
    }
    
    /// 设置最小权重阈值
    /// 只返回权重不低于指定值的实例
    pub fn with_min_weight(mut self, min_weight: f64) -> Self {
        self.min_weight = Some(min_weight);
        self
    }
    
    /// 设置最大实例数限制
    /// 限制返回的服务实例数量上限
    pub fn with_max_instances(mut self, max_instances: usize) -> Self {
        self.max_instances = Some(max_instances);
        self
    }
    
    /// 检查服务实例是否符合过滤条件
    /// 返回true表示实例通过所有过滤条件
    pub fn matches(&self, instance: &ServiceInstance) -> bool {
        // 健康状态过滤
        if self.healthy_only && !instance.healthy {
            return false;
        }
        
        // 元数据过滤
        for (key, value) in &self.metadata_filters {
            if instance.metadata.get(key) != Some(value) {
                return false;
            }
        }
        
        // 版本过滤
        if let Some(version) = &self.version_filter {
            if instance.metadata.get("version") != Some(version) {
                return false;
            }
        }
        
        // 集群过滤
        if let Some(cluster) = &self.cluster_filter {
            if instance.cluster.as_ref() != Some(cluster) {
                return false;
            }
        }
        
        // 环境过滤
        if let Some(env_filter) = &self.environment_filter {
            if !instance.matches_environment(env_filter) {
                return false;
            }
        }
        
        // 权重过滤
        if let Some(min_weight) = self.min_weight {
            if instance.weight < min_weight {
                return false;
            }
        }
        
        true
    }
}

/// 服务接口 trait
///
/// 定义了微服务的基本接口和行为。所有的服务实现都必须实现此 trait。
/// 提供了统一的服务调用接口，支持异步操作和类型安全。
///
/// # 主要方法
///
/// * `call` - 执行服务调用，接收请求并返回响应
/// * `name` - 获取服务名称，用于标识和路由
/// * `version` - 获取服务版本，用于版本管理和兼容性
///
/// # 使用示例
///
/// ```rust
/// use rustcloud_core::traits::Service;
/// use rustcloud_core::{Request, Response, ServiceResult};
/// use async_trait::async_trait;
///
/// struct UserService;
///
/// #[async_trait]
/// impl Service for UserService {
///     async fn call(&self, request: Request) -> ServiceResult<Response> {
///         // 处理用户服务请求
///         Ok(Response::new(200))
///     }
///     
///     fn name(&self) -> &str {
///         "user-service"
///     }
///     
///     fn version(&self) -> &str {
///         "1.0.0"
///     }
/// }
/// ```
#[async_trait]
pub trait Service: Send + Sync {
    /// 执行服务调用
    /// 
    /// 接收请求对象，处理业务逻辑，并返回响应对象。
    /// 所有的异常都应该被捕获并转换为 ServiceError。
    async fn call(&self, request: Request) -> ServiceResult<Response>;
    
    /// 获取服务名称
    /// 
    /// 返回唯一标识该服务的名称，用于服务注册和发现。
    fn name(&self) -> &str;
    
    /// 获取服务版本
    /// 
    /// 返回服务的版本号，用于版本管理和应用升级。
    fn version(&self) -> &str;
}

/// 服务注册中心 trait
///
/// 定义了服务注册发现的核心接口，支持服务实例的注册、注销、发现和监听功能。
/// 这是微服务架构中最重要的组件之一，负责维护服务拓扑和实现服务间通信。
///
/// # 核心功能
///
/// * **服务注册** - 将服务实例信息注册到注册中心
/// * **服务注销** - 从注册中心移除服务实例
/// * **服务发现** - 查询可用的服务实例列表
/// * **健康监控** - 监控服务实例的健康状态
/// * **事件监听** - 监听服务变化事件
///
/// # 实现要求
///
/// * 必须是线程安全的 (Send + Sync)
/// * 所有方法都是异步的，支持高并发
/// * 错误处理应该返回 ServiceResult
/// * 支持服务过滤和元数据查询
///
/// # 使用示例
///
/// ```rust
/// use rustcloud_core::traits::{ServiceRegistry, ServiceFilter};
/// use rustcloud_core::ServiceInstance;
///
/// async fn example_usage(registry: &dyn ServiceRegistry) {
///     // 注册服务实例
///     let instance = ServiceInstance::new("user-service", "127.0.0.1", 8080, "http");
///     registry.register(instance).await.unwrap();
///     
///     // 发现服务实例
///     let instances = registry.discover("user-service").await.unwrap();
///     
///     // 使用过滤器发现服务
///     let filter = ServiceFilter::new().healthy_only(true);
///     let healthy_instances = registry.discover_with_filter("user-service", filter).await.unwrap();
/// }
/// ```
#[async_trait]
pub trait ServiceRegistry: Send + Sync {
    /// 注册服务实例
    /// 
    /// 将服务实例注册到注册中心，使其可以被其他服务发现。
    /// 注册成功后，实例将出现在服务发现的结果中。
    async fn register(&self, instance: ServiceInstance) -> ServiceResult<()>;
    
    /// 带元数据的服务注册
    /// 
    /// 在注册服务实例的同时附加额外的元数据信息。
    /// 元数据可以用于服务路由、负载均衡策略选择等场景。
    async fn register_with_metadata(&self, instance: ServiceInstance, metadata: HashMap<String, String>) -> ServiceResult<()> {
        let mut enhanced_instance = instance;
        enhanced_instance.metadata.extend(metadata);
        self.register(enhanced_instance).await
    }
    
    /// 带健康检查的服务注册
    /// 
    /// 注册服务实例的同时配置健康检查规则。
    /// 注册中心将定期执行健康检查，自动更新实例的健康状态。
    async fn register_with_health_check(&self, instance: ServiceInstance, health_check: HealthCheck) -> ServiceResult<()> {
        // 默认实现，子类可以重写以支持健康检查
        self.register(instance).await
    }
    
    /// 注销服务实例
    /// 
    /// 从注册中心移除指定的服务实例。
    /// 注销后，该实例将不再出现在服务发现的结果中。
    async fn deregister(&self, instance: ServiceInstance) -> ServiceResult<()>;
    
    /// 发现服务实例
    /// 
    /// 根据服务名称查询注册中心中的所有可用实例。
    /// 返回的实例列表包含服务的完整信息，用于负载均衡和路由选择。
    async fn discover(&self, service_name: &str) -> ServiceResult<Vec<ServiceInstance>>;
    
    /// 带过滤器的服务发现
    /// 
    /// 使用指定的过滤器条件来筛选服务实例。
    /// 支持基于健康状态、元数据、版本等多维度的过滤。
    async fn discover_with_filter(&self, service_name: &str, filter: ServiceFilter) -> ServiceResult<Vec<ServiceInstance>> {
        let instances = self.discover(service_name).await?;
        
        let mut filtered_instances: Vec<ServiceInstance> = instances
            .into_iter()
            .filter(|instance| filter.matches(instance))
            .collect();
        
        Ok(filtered_instances)
    }
    
    /// 检查服务健康状态
    /// 
    /// 查询指定服务的所有实例并检查它们的健康状态。
    /// 通常用于健康检查和服务可用性监控。
    async fn health_check(&self, service_name: &str) -> ServiceResult<Vec<ServiceInstance>>;
    
    /// 监听服务变化
    /// 
    /// 创建一个服务监听器来监听指定服务的变化事件。
    /// 当服务实例发生增删改时，监听器会收到相应的事件通知。
    async fn watch(&self, service_name: &str) -> ServiceResult<Box<dyn ServiceWatcher + Send>>;
    
    /// 监听服务变化事件
    /// 
    /// 创建服务变化事件监听器，监听服务实例的增加、删除和更新事件。
    /// 默认实现使用 watch 方法，子类可以重写以提供更丰富的功能。
    async fn watch_service_changes(&self, service_name: &str) -> ServiceResult<Box<dyn ServiceWatcher + Send>> {
        // 默认使用 watch 方法
        self.watch(service_name).await
    }
    
    /// 获取所有服务列表
    /// 
    /// 返回注册中心中所有已注册服务的名称列表。
    /// 默认实现返回空列表，子类应该重写此方法。
    async fn list_services(&self) -> ServiceResult<Vec<String>> {
        // 默认实现返回空列表，子类可以重写
        Ok(Vec::new())
    }
    
    /// 获取注册中心的健康状态
    /// 
    /// 检查注册中心自身的健康状态和可用性。
    /// 用于监控注册中心的运行状态和连接状态。
    async fn registry_health(&self) -> ServiceResult<bool> {
        // 默认返回 true，子类可以重写
        Ok(true)
    }
}

/// 请求上下文信息
///
/// 包含了处理服务请求时所需的上下文信息，包括用户身份、会话、追踪和头部信息。
/// 这些信息可以用于负载均衡策略选择、会话保持和请求路由。
///
/// # 字段说明
///
/// * `session_id` - 会话标识符，用于会话保持和会话亲和性
/// * `user_id` - 用户标识符，用于用户级别的路由和负载均衡
/// * `trace_id` - 追踪标识符，用于分布式追踪和链路分析
/// * `headers` - HTTP头部信息，包含请求的元数据
/// * `remote_addr` - 客户端地址，用于地理位置路由和安全控制
#[derive(Debug, Clone)]
pub struct RequestContext {
    /// 会话标识符
    pub session_id: Option<String>,
    /// 用户标识符
    pub user_id: Option<String>,
    /// 分布式追踪标识符
    pub trace_id: Option<String>,
    /// HTTP请求头部
    pub headers: HashMap<String, String>,
    /// 客户端远程地址
    pub remote_addr: Option<String>,
}

/// 服务实例性能指标
///
/// 记录服务实例的实时性能数据，用于负载均衡策略决策和服务健康监控。
/// 这些指标可以帮助识别性能瘦弱的实例，实现智能负载均衡。
///
/// # 指标类型
///
/// * `response_time` - 平均响应时间，用于性能评估
/// * `success_rate` - 成功率(0.0-1.0)，用于质量评估
/// * `active_connections` - 活跃连接数，用于负载评估
/// * `cpu_usage` - CPU使用率(0.0-1.0)，系统资源指标
/// * `memory_usage` - 内存使用率(0.0-1.0)，系统资源指标
/// * `last_updated` - 最后更新时间，用于数据新鲜度判断
#[derive(Debug, Clone)]
pub struct InstanceMetrics {
    /// 平均响应时间
    pub response_time: Duration,
    /// 成功率 (0.0-1.0)
    pub success_rate: f64,
    /// 当前活跃连接数
    pub active_connections: u32,
    /// CPU使用率 (0.0-1.0)
    pub cpu_usage: f32,
    /// 内存使用率 (0.0-1.0)
    pub memory_usage: f32,
    /// 数据最后更新时间
    pub last_updated: std::time::SystemTime,
}

/// 负载均衡策略信息
///
/// 描述负载均衡策略的基本信息和特性，用于策略选择和配置。
/// 帮助用户理解不同策略的适用场景和限制条件。
///
/// # 策略特性
///
/// * `name` - 策略名称，用于显示和识别
/// * `description` - 策略描述，说明适用场景和特点
/// * `requires_session_affinity` - 是否需要会话亲和性支持
/// * `supports_weighted_routing` - 是否支持加权路由
#[derive(Debug, Clone)]
pub struct StrategyInfo {
    /// 策略名称
    pub name: String,
    /// 策略详细描述
    pub description: String,
    /// 是否需要会话亲和性
    pub requires_session_affinity: bool,
    /// 是否支持加权路由
    pub supports_weighted_routing: bool,
}

/// 负载均衡器 trait
///
/// 定义了负载均衡策略的核心接口，用于在多个服务实例中选择最适合的实例来处理请求。
/// 支持多种负载均衡策略，包括轮询、加权轮询、随机、最少连接等。
///
/// # 核心功能
///
/// * **实例选择** - 根据策略从可用实例中选择最优实例
/// * **上下文感知** - 支持基于请求上下文的智能选择
/// * **性能监控** - 收集和利用实例性能数据进行决策
/// * **策略信息** - 提供策略的详细信息和特性
///
/// # 常见策略
///
/// * **轮询(Round Robin)** - 按顺序轮流选择实例
/// * **加权轮询(Weighted Round Robin)** - 按权重比例轮流选择
/// * **随机(Random)** - 随机选择实例
/// * **最少连接(Least Connections)** - 选择连接数最少的实例
/// * **最快响应(Fastest Response)** - 选择响应最快的实例
///
/// # 使用示例
///
/// ```rust
/// use rustcloud_core::traits::{LoadBalancer, RequestContext};
/// use rustcloud_core::ServiceInstance;
/// use async_trait::async_trait;
///
/// struct RoundRobinLoadBalancer {
///     counter: std::sync::atomic::AtomicUsize,
/// }
///
/// #[async_trait]
/// impl LoadBalancer for RoundRobinLoadBalancer {
///     async fn select(
///         &self,
///         _service_name: &str,
///         instances: &[ServiceInstance],
///     ) -> rustcloud_core::ServiceResult<Option<ServiceInstance>> {
///         if instances.is_empty() {
///             return Ok(None);
///         }
///         let index = self.counter.fetch_add(1, std::sync::atomic::Ordering::Relaxed) % instances.len();
///         Ok(Some(instances[index].clone()))
///     }
///
///     fn name(&self) -> &str {
///         "round-robin"
///     }
///
///     fn get_strategy_info(&self) -> StrategyInfo {
///         StrategyInfo {
///             name: "Round Robin".to_string(),
///             description: "轮询负载均衡策略".to_string(),
///             requires_session_affinity: false,
///             supports_weighted_routing: false,
///         }
///     }
/// }
/// ```
#[async_trait]
pub trait LoadBalancer: Send + Sync {
    /// 基础实例选择方法
    /// 
    /// 根据负载均衡策略从可用实例列表中选择一个实例。
    /// 这是最基本的选择方法，所有负载均衡器都必须实现此方法。
    async fn select(
        &self,
        service_name: &str,
        instances: &[ServiceInstance],
    ) -> ServiceResult<Option<ServiceInstance>>;
    
    /// 带上下文的实例选择方法
    /// 
    /// 在选择实例时考虑请求上下文信息，如用户ID、会话信息等。
    /// 支持会话亲和性、用户级路由等高级功能。
    /// 默认实现使用基础选择方法，子类可以重写以支持上下文感知。
    async fn select_with_context(
        &self,
        service_name: &str,
        instances: &[ServiceInstance],
        context: &RequestContext,
    ) -> ServiceResult<Option<ServiceInstance>> {
        // 默认实现使用基础选择方法
        self.select(service_name, instances).await
    }
    
    /// 更新实例性能指标
    /// 
    /// 收集服务实例的实时性能数据，用于智能负载均衡决策。
    /// 默认实现为空，支持性能感知的负载均衡器应该重写此方法。
    async fn update_instance_metrics(&self, instance: &ServiceInstance, metrics: InstanceMetrics) {
        // 默认实现为空，子类可以重写
    }
    
    /// 获取负载均衡策略信息
    /// 
    /// 返回策略的详细信息，包括名称、描述和特性支持情况。
    /// 用于策略选择和配置界面显示。
    fn get_strategy_info(&self) -> StrategyInfo;
    
    /// 获取负载均衡器名称
    /// 
    /// 返回负载均衡器的唯一标识符，用于日志记录和监控。
    fn name(&self) -> &str;
}

/// 传输层 trait
///
/// 定义了服务间通信的传输层抽象接口，支持多种协议和传输方式。
/// 负责将请求发送到指定的服务实例，并处理响应的接收和解析。
///
/// # 支持的传输协议
///
/// * **HTTP/HTTPS** - RESTful API和Web服务通信
/// * **gRPC** - 高性能的RPC通信
/// * **TCP/UDP** - 低级别的网络通信
/// * **WebSocket** - 实时双向通信
///
/// # 功能特性
///
/// * **单个请求** - 发送单个请求到指定实例
/// * **批量请求** - 同时发送多个请求以提高性能
/// * **连接管理** - 自动管理连接池和生命周期
/// * **错误处理** - 统一的错误处理和重试机制
#[async_trait]
pub trait Transport: Send + Sync {
    /// 发送单个请求
    /// 
    /// 将请求发送到指定的服务实例，等待并返回响应。
    /// 支持超时控制、重试和错误处理。
    async fn send(&self, request: Request, instance: &ServiceInstance) -> ServiceResult<Response>;
    
    /// 发送批量请求
    /// 
    /// 同时发送多个请求到不同的服务实例。
    /// 可以利用连接复用和并发处理来提高性能。
    async fn send_batch(
        &self,
        requests: Vec<(Request, &ServiceInstance)>,
    ) -> Vec<ServiceResult<Response>>;
    
    /// 获取传输层名称
    /// 
    /// 返回传输层实现的名称，用于日志记录和监控。
    fn name(&self) -> &str;
}

/// 熔断器配置
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CircuitBreakerConfig {
    pub enabled: bool,
    pub failure_rate_threshold: f64,     // 失败率阈值 (0.0-1.0)
    pub response_time_threshold: Duration, // 响应时间阈值
    pub min_request_threshold: u32,       // 最小请求数阈值
    pub failure_threshold: u32,          // 失败次数阈值
    pub recovery_timeout: Duration,       // 恢复超时时间
    pub half_open_success_threshold: u32, // 半开状态成功阈值
    pub fallback_enabled: bool,          // 是否启用降级
}

impl Default for CircuitBreakerConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            failure_rate_threshold: 0.5,
            response_time_threshold: Duration::from_millis(1000),
            min_request_threshold: 10,
            failure_threshold: 5,
            recovery_timeout: Duration::from_secs(30),
            half_open_success_threshold: 2,
            fallback_enabled: true,
        }
    }
}

/// 调用统计数据
#[derive(Debug, Clone)]
pub struct CallStats {
    pub total_calls: u64,
    pub successful_calls: u64,
    pub failed_calls: u64,
    pub average_response_time: Duration,
    pub last_call_time: Option<std::time::SystemTime>,
}

#[async_trait]
pub trait CircuitBreaker: Send + Sync {
    async fn call(
        &self,
        service_name: &str,
        func: Box<dyn FnOnce() -> std::pin::Pin<Box<dyn std::future::Future<Output = ServiceResult<Response>> + Send>> + Send>,
    ) -> ServiceResult<Response>;
    
    /// 带降级的调用
    async fn call_with_fallback<T, F, Fut, FB>(
        &self,
        service_name: &str,
        operation: F,
        fallback: FB,
    ) -> ServiceResult<T>
    where
        Self: Sized,
        T: Send + 'static,
        F: FnOnce() -> Fut + Send,
        Fut: std::future::Future<Output = ServiceResult<T>> + Send,
        FB: FnOnce() -> T + Send;
    
    async fn state(&self, service_name: &str) -> CircuitBreakerState;
    
    async fn metrics(&self, service_name: &str) -> CircuitBreakerMetrics;
    
    /// 获取调用统计
    async fn get_call_stats(&self, service_name: &str) -> ServiceResult<CallStats> {
        // 默认实现
        Ok(CallStats {
            total_calls: 0,
            successful_calls: 0,
            failed_calls: 0,
            average_response_time: Duration::from_millis(0),
            last_call_time: None,
        })
    }
    
    /// 重置熔断器状态
    async fn reset(&self, service_name: &str) -> ServiceResult<()>;
    
    /// 强制打开熔断器
    async fn force_open(&self, service_name: &str) -> ServiceResult<()>;
    
    /// 强制关闭熔断器
    async fn force_close(&self, service_name: &str) -> ServiceResult<()>;
}

/// 重试条件
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum RetryCondition {
    NetworkError,
    Timeout,
    HttpStatus(u16),
    HttpStatusRange(u16, u16),
}

/// 重试配置
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RetryConfig {
    pub max_attempts: u32,
    pub base_delay: Duration,
    pub max_delay: Duration,
    pub retry_on: Vec<RetryCondition>,
    pub budget_percent: f64,  // 重试预算百分比
}

/// 超时配置
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TimeoutConfig {
    pub connect_timeout: Duration,
    pub request_timeout: Duration,
    pub idle_timeout: Duration,
}

/// 连接池配置
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ConnectionPoolConfig {
    pub max_connections: usize,
    pub max_idle_connections: usize,
    pub connection_timeout: Duration,
    pub idle_timeout: Duration,
    pub keep_alive: bool,
}

/// 代理配置
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProxyConfig {
    pub retry: RetryConfig,
    pub timeout: TimeoutConfig,
    pub connection_pool: ConnectionPoolConfig,
    pub circuit_breaker: Option<CircuitBreakerConfig>,
}

/// 服务代理 trait
#[async_trait]
pub trait ServiceProxy: Send + Sync {
    /// 带重试的调用
    async fn call_with_retry(&self, request: Request) -> ServiceResult<Response>;
    
    /// 批量调用
    async fn batch_call(&self, requests: Vec<Request>) -> Vec<ServiceResult<Response>>;
    
    /// 获取调用统计
    async fn get_call_stats(&self) -> CallStats;
    
    /// 获取服务实例列表
    async fn get_available_instances(&self, service_name: &str) -> ServiceResult<Vec<ServiceInstance>>;
    
    /// 更新服务发现缓存
    async fn refresh_service_cache(&self, service_name: &str) -> ServiceResult<()>;
}

/// 服务监听器
#[async_trait]
pub trait ServiceWatcher: Send {
    async fn next_event(&mut self) -> ServiceResult<ServiceRegistryEvent>;
}

/// 指标收集器
#[async_trait]
pub trait MetricsCollector: Send + Sync {
    /// 创建计数器
    fn counter(&self, name: &str) -> Box<dyn Counter + Send + Sync>;
    
    /// 创建直方图
    fn histogram(&self, name: &str) -> Box<dyn Histogram + Send + Sync>;
    
    /// 创建仪表盘
    fn gauge(&self, name: &str) -> Box<dyn Gauge + Send + Sync>;
    
    /// 导出指标（Prometheus格式）
    async fn export_metrics(&self) -> ServiceResult<String>;
    
    /// 清理过期指标
    async fn cleanup_expired_metrics(&self) -> ServiceResult<()>;
}

/// 计数器 trait
pub trait Counter {
    fn increment(&self);
    fn increment_by(&self, value: u64);
    fn get(&self) -> u64;
}

/// 直方图 trait
pub trait Histogram {
    fn record(&self, value: f64);
    fn get_count(&self) -> u64;
    fn get_sum(&self) -> f64;
    fn get_percentile(&self, percentile: f64) -> f64;
}

/// 仪表盘 trait
pub trait Gauge {
    fn set(&self, value: f64);
    fn increment(&self);
    fn decrement(&self);
    fn get(&self) -> f64;
}

/// 分布式追踪提供者
#[async_trait]
pub trait TracingProvider: Send + Sync {
    /// 开始一个新的追踪范围
    async fn start_span(&self, name: &str) -> Box<dyn Span + Send + Sync>;
    
    /// 注入追踪上下文到HTTP头
    async fn inject_context(&self, headers: &mut HashMap<String, String>);
    
    /// 从HTTP头提取追踪上下文
    async fn extract_context(&self, headers: &HashMap<String, String>) -> Option<Box<dyn SpanContext + Send + Sync>>;
    
    /// 获取当前活跃的追踪上下文
    fn current_context(&self) -> Option<Box<dyn SpanContext + Send + Sync>>;
}

/// 追踪范围
pub trait Span {
    fn set_attribute(&self, key: &str, value: &str);
    fn set_status(&self, status: SpanStatus);
    fn add_event(&self, name: &str, attributes: HashMap<String, String>);
    fn finish(self);
}

/// 追踪上下文
pub trait SpanContext {
    fn trace_id(&self) -> String;
    fn span_id(&self) -> String;
    fn is_sampled(&self) -> bool;
}

/// 追踪范围状态
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum SpanStatus {
    Ok,
    Error,
    Timeout,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum ServiceRegistryEvent {
    InstanceAdded {
        service_name: String,
        instance: ServiceInstance,
    },
    InstanceRemoved {
        service_name: String,
        instance: ServiceInstance,
    },
    InstanceUpdated {
        service_name: String,
        instance: ServiceInstance,
    },
}